fix(types): give seven recursion-breaking zod mirrors their declaration as both type arguments - #8354

Fixes #7760

Executes the maintainer ruling of decision batch #69 (2026-09-07, reply verbatim 「同意」): the ten z.lazy mirrors annotated z.ZodType<any> get their existing TypeScript declaration as both type arguments, so the published input face of every slot that reaches them carries the node union instead of unknown. The runtime accept set does not move; @objectstack/spec is untouched; the TS declarations are untouched.

Ruled 乙 with 丙 as the per-const fallback, and the trial below is why that clause was written.

The trial, one const at a time

Each row is its own run: the const's annotation filled on an otherwise clean origin/main tree, then tsc --noEmit over packages/types. Order-dependent refusals were re-run in the combined tree, and the verdict column is the combined result.

The three refusals, verbatim from tsc:

src/zod/app.zod.ts(136,14): error TS2322: Type 'ZodLazy<ZodObject<...>>' is not assignable to
  type 'ZodType<NavigationItem, NavigationItem, $ZodTypeInternals<NavigationItem, NavigationItem>>'.
  The types of '_output.id' are incompatible between these types.
    Type 'string | undefined' is not assignable to type 'string'.

src/zod/complex.zod.ts(291,14): error TS2322: Type 'ZodLazy<ZodObject<...>>' is not assignable to
  type 'ZodType<FilterBuilderCondition, FilterBuilderCondition, ...>'.
  The types of '_output.operator' are incompatible between these types.
    Type '"in" | ... | "is_null" | "is_not_null"' is not assignable to type 'FilterBuilderOperator'.
      Type '"is_null"' is not assignable to type 'FilterBuilderOperator'.

src/zod/complex.zod.ts(320,14): error TS2322: Type 'ZodLazy<ZodObject<...>>' is not assignable to
  type 'ZodType<FilterGroup, FilterGroup, ...>'.
  The types of '_input.conditions' are incompatible between these types.
    Type 'unknown[]' is not assignable to type '(FilterGroup | FilterBuilderCondition)[]'.

The ruling's stated cause for the fallback did not occur, and a different one did

The execution note conditions the 丙 fallback on the TS declaration being derived from the zod schema (z.infer / z.input), which would re-close the inference cycle. That did not happen on any of the ten. All ten declarations are hand-written interface / type (checked: no z.infer or z.input of a local mirror anywhere in the declaration files), and no run produced a circularity diagnostic.

What the three refusals are instead: the mirror already accepts more than its declaration states, so the assignment tsc performs to check the annotation is the wider-direction comparison, and it fails.

• NavigationItemSchema — the mirror declares id optional (deliberately, so a bare { type: 'separator' } parses); NavigationItem.id is required.
• FilterBuilderConditionSchema — the mirror's operator enum carries is_null / is_not_null; FilterBuilderOperator carries is_empty / is_not_empty instead.
• FilterGroupSchema — its conditions union names FilterBuilderConditionSchema, so it follows the one above.

Measured, not assumed: filling only the INPUT position (z.ZodType<any, NavigationItem>) fails identically, on _input.id and _input.operator. Closing either would need a runtime accept-set change or a declaration change, both of which the ruling forbids — so these three keep the annotation and stay with 丙, which is where the ruling's fallback puts them. The trigger for that branch is wider than the ruling predicted, and this PR does not narrow it silently.

The parity ledger can now see the region it had excluded

packages/types/src/__tests__/zod-mirror-parity.test.ts — the ledger from #7069 / PR #7758 — excluded every slot whose input face was unknown, which is exactly the z.union([SchemaNodeSchema, z.array(SchemaNodeSchema)]) single-or-list producer that card called systematic. Re-run on this branch:

The "before" column is derived on this PR's base commit by the same instrument, not quoted from any card — and it reproduces the header's own figures exactly, which is what makes the "after" column readable.

19 keys across 16 pairs left (13 entries emptied): the reading they recorded was the annotation, not an accept-set gap. 3 keys entered, all three real widenings the erased face had been hiding, all three the single-or-list spelling:

• feedback.zod.ts#ToastSchema::action — mirror SchemaNode | SchemaNode[], declaration { label: string; onClick: () => void }. DISJOINT, so it enters KnownDrift too. Note the declaration is the suspect face: ToastSchema.onDismiss sits one member below it as a finding(types): 28 zod-mirror keys are declared z.function(), which NO JSON document can satisfy — 14 in-repo corpus files author them and are silently invalid #6124 tombstone telling authors to "author behaviour as a node type", which is what the mirror already accepts.
• navigation.zod.ts#HeaderBarSchema::logo — mirror SchemaNode | SchemaNode[], declaration logo?: string.
• overlay.zod.ts#TooltipSchema::content — mirror SchemaNode | SchemaNode[], declaration content?: string | SchemaNode: the same union without the list arm, while the sibling body on the same pair declares the list and agrees.

None of the three is repaired here — the ruling's scope is the type argument. They are ledgered, with both faces named, for 丙's lane.

The runtime walk leg is unchanged and still pins the region's sources; its docblock now says why the list keeps all ten names even though seven no longer produce a blind face (it detects z.lazy nodes, which is what makes an eleventh visible).

assertionSchemaNodeFaceIsUnconstrained fired on the first compile, exactly as its own note said it would. It is kept, inverted, and a second line was added on NavigationItemSchema so the exclusion's remaining members are pinned from the other side too — a revert of either annotation is red rather than silently unmeasured.

Verification

• pnpm --filter @object-ui/types type-check — exit 0 (three projects: tsc --noEmit, tsconfig.examples.json, tsconfig.test.json; the ledger's ratchets are compile-time assertions read by the third).
• vitest run --project unit packages/types/src/__tests__ — 141 files, 2695 tests passed on the merged head.
• vitest run --project unit (whole repo, pre-merge head) — 960 files, 16230 passed, 2 skipped.
• turbo run build --concurrency=2 --filter='!@object-ui/site' — 43/43 successful.
• turbo run type-check --concurrency=2 --filter='...@object-ui/types' — 77/77 successful. Direction declared: ...<pkg> is the package and its dependents, i.e. every downstream consumer of the changed published types.
• Gates, each run with the exit code captured before any pipe: check:element-data-source-declaration · check:sdui-registration-pins · check:spec-symbols · check:spec-floors · check:doc-types · check:doc-snippets · check:doc-fences · check:readme-exports · check:control-bytes · check:handler-key-reads · check:self-import · check:phantom-deps — all exit 0.
• Lint: pnpm --filter @object-ui/types lint exit 0 (206 files linted, 0 errors, 266 pre-existing no-explicit-any warnings — seven fewer than before, since seven z.ZodType<any> annotations are gone) and pnpm run lint:root exit 0. Narrowed deliberately: the diff touches one package plus .changeset/, and this repo's lint gate is per-package (turbo run lint), so the other 43 packages have no changed file; eslint.config.js enables no type-aware linting (no project / projectService), so nothing in this diff can move a verdict on a file it does not contain.

Reverse verification (the published face really did narrow, read from the built .d.ts)

A consumer-side probe resolving @object-ui/types/zod through the package exports — so through dist, not the source alias — assigning a function value into z.input<typeof AppMenuItemSchema>:

The two dist blob hashes differ, so the second leg is a real rebuild and not a cache read. The ablation and probe were removed afterwards; git status and git diff HEAD are both empty and the dist blob is back to cbfb6b4.

Declared deviation

packages/types/src/__tests__/app-action-onclick-refusal-6854.test.ts is outside the declared file surface and carries a one-line consequential edit. AppActionSchema.items used to infer as any[] because its element mirror was the erased MenuItemSchema; it is AppMenuItem[] now, so a direct type assertion to { items: Record<string, unknown>[] } no longer overlaps and tsc refuses it (TS2352). The repair routes that one assertion through unknown and adds the reason. No assertion in the file changed, and the file's subject — that both undeclared keys are gone from the parsed value at runtime — is untouched. Reported rather than absorbed: without it the ruled change cannot compile at all.

Serial constraints

• #7918 (same ten consts, different change) is CLOSED, completed by merged PR fix(types): memoise the two zod lazy getters that can be, pin why the other eight cannot (objectui#7918) #8226 (4f9f1ee, which memoised two of the lazy getters). This PR touches no getter — verified at contract review. ⚠️ The earlier text here said it "rebases after this lands"; that is stale and is corrected rather than left. ⛔ It also spelled a delivery-declaration keyword immediately beside another card's number, in an accounting sentence — which makes prDeliversCard report a delivery that does not exist and manufactures a phantom carrier-split row (objectstack#16706, measured with a two-sided control). Respelled here with zero verbs beside the card number.
• #8324 and #8330 consume SchemaNodeSchema without editing any file on this surface. origin/main was merged in at 411a132 after both had landed, pnpm install re-run, and the full packages/types type-check and test suite re-run green on the merge commit — including the ledger's ratchets against #7105's new EmptySchema.action: SchemaNode declaration.
• #7759 is deferred behind this card; the parity ledger was held serially for exactly this reason.

Review

packages/types is not a governed surface (triage's correction, upheld by the ruling): ordinary merge queue. But this is a published type-face change, so clause ② applies: needs:contract-review is on the card and on this PR, the PR stays draft, and auto-merge is not armed. Only a CONTRACT_REVIEW_TIER reviewer clears the two carriers.

Generated by Claude Code

Generated by Claude Code